home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 June / EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso / earcd / comm2 / xraid123.lha / DOC / XRaid.doc < prev    next >
Text File  |  1995-08-23  |  22KB  |  489 lines
  1.   
  2.  
  3.                    XRaid - FileEcho AreaMGR for the Amiga
  4.        Copyright (c) 1995 by Robert Williamson, FIDONET#1:167/104.0
  5.                             ALL RIGHTS RESERVED
  6.  
  7.         This  software  is  provided  "as  is",  without warranty and/or
  8.     guarantee  of any kind.  You may use and/or distribute this software
  9.     and copies of it, as long as no alterations have been made, no files
  10.     have  been  added  to/omitted from the original distribution archive
  11.     and no charge is asked for.
  12.         This package may be freely distributed via BBSs, ADS, AmiNet and
  13.     software libraries such as Fred Fish's and Aminet CD-ROMs, and other
  14.     similar electronic channels.
  15.  
  16.         This package may NOT be distributed by SAN or by Disk magazines,
  17.     PD  libraries  or  BBSs  and  Services  that  charge  extra for file
  18.     transfers  without  authorization  from,  and  compensation  to  the
  19.     author.
  20.  
  21.  
  22.   What is an AreaMGR?
  23.     AreaMGR  is  the generic term to describe a program that processes user
  24.   requests  to  link and unlink from echos.  Although the specification for
  25.   AreaMGRs  as defined in fsc-0057 is for message echos (now referred to as
  26.   ConfMGR),  the  syntax  has  now  come  to be applied to file echos also.
  27.     FSC-0057 defines both the minimum command set and extensions to be used
  28.   for  such programs.  Additional command extensions as defined by a number
  29.   of  other FileEcho AreaMGRs (such as AllFix and Seal) have also come into
  30.   common  usage.   XRaid  supports most, if not all, of the minimum command
  31.   set as well as many of the extensions.  Note that AllFix DOES NOT support
  32.   the basic FSC-0057 command set. 
  33.     
  34.  
  35.     An AreaMGR performs four basic FTN functions:
  36.  
  37.       - Parses a request from a user to add, remove or list FileEchos.
  38.       - Checks users password and access level.
  39.       - notifies user of the results of his request.
  40.       - Updates the configuration.
  41.  
  42.     XRaid does much more.
  43.  
  44.   Status of This Release:
  45.     This  is  BETA  and  given the great number of features it probably has
  46.   bugs.  In the case of a serious ERROR, and if the error conditions allow,
  47.  
  48.               XRaid WILL AUTOMATICALLY WRITE A MESSAGE to ME
  49.                                 at  either
  50.                FIDONET#1:167/104.0 or AMIGANET#40:600/104.0.
  51.  
  52.     BE  SURE  that you have set these addresses as ROUTED in your tosser or
  53.   packer/router   config   BEFORE  running  XRaid,  so  as  not  to  incure
  54.   long-distance charges.
  55.  
  56.     The  LogLevel  for  log messages is presently set quite low in order to
  57.   display  a  lot  of progress info for debugging.  At a LOGLEVEL of 3, the
  58.   log  will  grow very fast.  At a later date, loglevels will be changed to
  59.   insure a minimal amount of info for normal processing.
  60.  
  61.     This  documentation may not be always up to date, as features are being
  62.   added  at  a  very quick pace.  Refer to the example XTick.cfg for config
  63.   changes and the XRaid USAGE display for command line changes.
  64.  
  65.     The  ToDo  list  is  changed  daily, items being either implemented and
  66.   removed  from  the list or new items added.  There is no obligation on my
  67.   part to implement anything in the ToDO list unless a contract to do so is
  68.   entered into by myself and a customer.
  69.  
  70.   Copyrights:
  71.     XRaid, XRaid.doc and the format of XTick.cfg are all,
  72.        Copyright (c) 1995 by Robert Williamson, FIDONET#1:167/104.0
  73.  
  74.   Requirements:
  75.     WB 2.1 MINIMUM
  76.     rexxdossupport.library v2.3
  77.     The  AmigaOS commands List and Assign must be either resident or on the
  78.     path.
  79.  
  80.   Features:
  81.     o pure, residentable
  82.     o multi-ftn
  83.     o supports BOTH XferQ and Flow File systems
  84.     o uses XTick config file
  85.     o advanced config format allows multiple keywords per line
  86.     o GLOBAL options can be overidden by SITE or AREA options
  87.     o SITE options can be overidden by SITE's AREA options
  88.     o SITE and AREA passwords 
  89.     o config report to all or one SITE
  90.     o extensive command parameter substitution available
  91.     o configurable commands w/substitution for packing and importing
  92.     o multiple commands can be defined for all types
  93.     o displayable SITE config, AREA config and GLOBAL config
  94.     o notification message for all errors in user request
  95.     o will also use RoofLog function host if active.
  96.     o compliant with fsc-0057 and compatible with AllFix
  97.  
  98.   See ToDO for future features.
  99.  
  100.   Installation:
  101.     Be  sure that your dearc command preserves attributes.  If it does not,
  102.   run:
  103.     > Protect Mail:XRaid pwerd
  104.  
  105.     Copy  XRaid  to  somewhere  on  your  path, MAIL:  is nice.  For faster
  106.   loading, you can pre-load them as resident with this commands:
  107.     > Resident Mail:XRaid ADD
  108.  
  109.     Be SURE you do not have any other program called XRaid on your path.
  110.  
  111.     If  you do not have a CFG:  assign, create one and place your XTick.CFG
  112.   there.   Otherwise,  you  will  have  to  specify the CFGFILE path on the
  113.   commandline.   If  you are going to do it anyways, then a good idea is to
  114.   copy the config to RAM:  in your startup and use
  115.           CFGFILE RAM:XTick.CFG 
  116.   in your XRaid command lines.  This will speed up operations as bit more.
  117.  
  118.     Copy  rexxdosupport.library  and rexxplslib.library to any directory of
  119.   your LIBS:  assign.
  120.  
  121.    Copy  Start-ARexx  to  S:.   Then  remove  the call to RexxMast in your
  122.   S:Startup-Sequence and add a call to S:Start-ARexx to your S:User-Startup.
  123.   
  124.     Copy RPStart#? to your SYS:WBstartup directory. 
  125.  
  126.  
  127.   Templates: 
  128.     XTick  uses standard AmigaDos Templates for both command line arguments
  129.   and  for  many  configuration  items.  See Xconfig.DOC for explanation of
  130.   templates used.
  131.  
  132.   Command Line Usage:
  133.     The  various  modes  allows  use  of  XTick in WhenRecd, TurnAround and
  134.   AfterSession  commands as well as in a cli.  The template is divided into
  135.   functional sets.  A Set is defined by the first parameter you give.
  136.  
  137.     DEBUG  and  CFGFILE  may  be used with any set, but may not be the last
  138.   items  in  the  command  line  if  a /F template is specified in the set.
  139.   Template  parameters  that  are  not  valid for the set are ignored.  The
  140.   template below shows each Set.
  141.     Any  of the addressing formats defined above can be used on the command
  142.   line.
  143.  
  144.     Template:
  145.     SHOWCFG/S
  146.     SHOWSITE/K,SHOWAREA/K,
  147.     REPORT/K,
  148.     SENDHELP/K,
  149.     SENDSTATUS/K,
  150.     GETHELP/K,
  151.     GETSTATUS/K,
  152.     SENDCMD/K,CMD/K/F,
  153.     RAIDLIST/K,
  154.     DEBUG/S,CFGFILE/K,LOGLEVEL/K (all sets)
  155.  
  156.  
  157.     SHOWCFG [CFGFILE ...] [DEBUG]
  158.       Displays configuration
  159.  
  160.     SHOWAREA filearea [CFGFILE ...] [DEBUG]
  161.       Display configuration for an FILEAREA
  162.  
  163.     SHOWSITE address|ALL [CFGFILE ...] [DEBUG]
  164.       Display options for a site and areas to which it is connected
  165.  
  166.     REPORT address|ALL  [CFGFILE ...] [DEBUG]
  167.       Sends  a  status and areas report to site.  If site is ALL, this will
  168.       send  reports  to ALL configured sites INCLUDING those configured for
  169.       NOREPORT. 
  170.       usage in cron: 30 03 * * 1 XTick REPORT ALL
  171.  
  172.     SENDHELP address|ALL  [CFGFILE ...] [DEBUG]
  173.       Sends  the help file as a message to site.  If site is ALL, this will
  174.       send the help message to ALL configured sites.
  175.  
  176.     SENDSTATUS address|ALL  [CFGFILE ...] [DEBUG]
  177.       Sends  a  site  status  report as a message to site.  If site is ALL,
  178.       this will send status reports to ALL configured sites.
  179.  
  180.     GETSTATUS [progname@]address|ALL|UPLINKS
  181.       Sends  request  for  Status  from  site.   
  182.       If address is ALL, sends requests to ALLFIX at ALL configured sites.
  183.       If address is UPLINKS, send request to configured manager program for
  184.       site.
  185.       If  a  single address is specified, and the progname@ option is used,
  186.       the  request  is  sent  to that program name, otherwise it is sent to
  187.       ALLFIX.  The message is sent with the From name in the config keyword
  188.       SYSOP.
  189.  
  190.     GETHELP [progname@]address|ALL|UPLINKS
  191.       Sends  request  for usage instructions from site.
  192.       If address is ALL, sends requests to ALLFIX at ALL configured sites.
  193.       If address is UPLINKS, send request to configured manager program for
  194.       site.
  195.       If  a  single address is specified, and the progname@ option is used,
  196.       the  request  is  sent  to that program name, otherwise it is sent to
  197.       ALLFIX.  The message is sent with the From name in the config keyword
  198.       SYSOP.
  199.  
  200.    SENDCMD [progname@]address CMD cmdstring;cmdstring;cmdstring
  201.       Sends a ";" separated command string to address. The ; is converted
  202.       to CR in the message.
  203.       If  a  single address is specified, and the progname@ option is used,
  204.       the  request  is  sent  to that program name, otherwise it is sent to
  205.       ALLFIX.  The message is sent with the From name in the config keyword
  206.       SYSOP.
  207.  
  208.     CFGFILE fullpathname
  209.       Defines  the  fullpath  name  for  the XTick configuration file.  The
  210.       default is CFG:XTICK.CFG
  211.  
  212.     MSG fullpathname
  213.       The defined MSG file is read and processed.
  214.  
  215.     RAIDLIST fullpathname
  216.       The  defined RaidListfile is read and processed.  The RaidList is the
  217.       output  of  a  packet scanning program. 
  218.       This function requires a packet scanner, such as XScan.
  219.  
  220.     DEBUG
  221.       Displays  VERBOSE  info  and is valid with each operating mode.  When
  222.       DEBUG  is  set,  the window is not opened, everything is displayed in
  223.       the  current  CLI.   The amount of info displayed is MASSIVE.  In the
  224.       case of reported bugs, a copy of this will be required.
  225.  
  226.     LOGLEVEL
  227.       Overides the LOGLEVEL setting in the config file.
  228.  
  229.  
  230.   Configuration:
  231.     The  default fullpathname of the config file is CFG:XTick.cfg.  You can
  232.   specify an alternate fullpathname on the command line.
  233.  
  234.     Please  see Xconfig.DOC for explanation of config file format, keywords
  235.   and templates.
  236.  
  237.     When  updating  the  configuration  file, XRaid reformats and re-orders
  238.   various  items.   In particular, please note that all SITEAKA entries are
  239.   replaced  by  full  SITE entries.  XRaid always re-reads the config after
  240.   writing, and reports any error found.
  241.  
  242.   Addressing:
  243.     Addresses  can  be  specified in a number of formats in both the config
  244.   and  on  the  command  line,  the  preferred  being  FQFA.   The  minimum
  245.   acceptable  is  3d  (z:net/node.) for FidoNet and FTNS listed in FTNLIST.
  246.   All other FTNs must be specified as 5D or FQFA.
  247.  
  248.         Address Formats:
  249.             FQFA  -   ftn#zone:net/node.point   (all must be present)
  250.             5d    -   zone:net/node[.point]@ftn (if no point, 0 is assumed)
  251.             4d    -   zone:net/node.point
  252.             3d    -   zone:net/node
  253.  
  254.   
  255.   Reports:
  256.     Unlike the XTick version of the REPORT command, XRaid's REPORT does NOT
  257.   respect  a  setting  of  NOREPORT  for a site.  This allows you to send a
  258.   REPORT to a site that has turned reports off via the %NOTIFY command. The
  259.   following  command will send the REPORT.  This report is a full report of
  260.   a  site's status, permissions and areas.  This is the same report that is
  261.   sent in response to a %QUERY command.
  262.  
  263.           XRaid REPORT <address|ALL>
  264.  
  265.     The  SENDSTATUS  command  will  send  a  report  of a sites' status and
  266.   permissions,  the area report not being included.  The same status report
  267.   is sent in response to the %STATUS command.
  268.  
  269.     Reports  will  be  written  as  packets in the global OUT directory and
  270.   packed/routed by the defined PACKER command.
  271.   
  272.  
  273.   Get Commands:
  274.     The  SENDCMD  command  permits  sending  any  area manager command to a
  275.   configured  site.  The ALL and UPLINKS options is not valid with SENDCMD.
  276.   Multiple commands are permitted, if separated by semi-colons (;). The ;
  277.   are converted to CRs in the message.
  278.     eg:
  279.       XRaid SENDCMD 1:167/0 CMD %NOTIFY OFF;%MESSAGE OFF
  280.      or
  281.       XRaid SENDCMD RAID@1:167/0 CMD %NOTIFY OFF;%MESSAGE OFF
  282.   
  283.  
  284.     The GETHELP and GETSTATUS commands are provided to simplify sending the
  285.   commands  %HELP  and  %STATUS  to one site, all uplinks or all configured
  286.   sites.   The  messages  are  sent  using  the  name  defined  as SYSOP in
  287.   Xtick.cfg  as  the From name.  This is necessary to prevent an endless of
  288.   exchange of messages between the two robots.  This can occur if the other
  289.   site requires the sysop name.
  290.  
  291.   Uplinks and Request Forwarding:
  292.     When  a  downlink which has the FWDREQ permission set, requests an area
  293.   that  we  do  not  have, XRaid will search for the AREA in the configured
  294.   FILEBONE  listing and try to find the FDN in is GROUPSLISTs.  If the area
  295.   is  found,  XRaid will then search the configured UPLINKS for a site that
  296.   is  in  the  same Group for that FDN (File Distribution Network) for that
  297.   area.   If  one  is  found, and the requesting site is authorized for the
  298.   Group, a message is sent to the area MANAGER of that site, requesting the
  299.   area. The information for the new area is stored in a RAIDDATA file. This
  300.   file will be used by XTick to add the new AREA when files are received.
  301.     
  302.   FileBone:
  303.     The  FileBone  is  a  network  of  sites, similar to the Echo BackBone,
  304.   except  that  these site distribute FileEchos.  The FileEchos distributed
  305.   by  the  FileBone  are  listed  in  the file FILEBONE.NA which is updated
  306.   weekly and   distributed in the appropriately named FileEcho, FILEBONE. 
  307.  
  308.     The  format of FILEBONE.NA is documented and XRaid can read this format
  309.   to  find  requested  FileEchos.  The particular fields XRaid uses are the
  310.   names  of  the  FileEcho  and the FDN (File Distribution Network) and the
  311.   descriptions of the FileEcho and FDN.
  312.   
  313.   FileBone listing format:
  314.   The  following  format  is used to describe each of the File Distribution
  315.   Nets.
  316.  
  317.      Kywd FileTag   Level Flags                  Description
  318.      ---- --------  ----  -----  --------------------------------------------
  319.      Area XYZ_GIF   0     !      XYZ: GIF files for the XYZ program
  320.      ^              ^     ^      ^                                          ^
  321.  COL:1              1     2      2                                          7
  322.                     6     2      9                                          8
  323.  
  324.  
  325.          "Area"  - Used by RAID (thanks George!) and similar programs to
  326.                    denote the beginning of an file area definition.
  327.  
  328.          FileTag - Name of area that files will be sent under.  Similar to an
  329.                    echomail areatag, but limited to 8 characters or less.
  330.  
  331.          Level   - Security level (0-4096) used to protect this area
  332.  
  333.          Flags   - Access flags (see below) to control who's allowed to feed,
  334.                    and what type of echo it is.
  335.  
  336.          Desc    - FDN abbreviation followed by a description of the area's
  337.                    contents.
  338.  
  339.  There are five types of access flags:
  340.  
  341.      "!" - Filebone distribution.  Areas marked with this flag are carried by
  342.            the Filebone and can found at any Filebone Hub site (see below).
  343.  
  344.      "." - Open distribution.  While unrestricted in nature, these areas are
  345.            *NOT* distributed by the Filebone.  Although many Filebone Hubs do
  346.             in fact carry them, you may be forced to find your own feed.
  347.  
  348.      "*" - Hatching is allowed by *any* node attached to the area.  This flag
  349.            may be mixed with any of the others.  If an area does not contain
  350.            this flag, then you may not hatch directly into it.  There will
  351.            either be a "return channel" provided or you must send your
  352.            submission directly to the FDN head or other listed site.
  353.  
  354.      "&" - Do not send this area to any downlinks.  This flag usually
  355.            indicates that an area is a "return channel" to be used for
  356.            submitting files to a FDN head for distribution.  Be sure to
  357.            remove it in your TIC.CFG for your uplink *only*.  This flag
  358.            should only be used in conjunction with the "*" flag.
  359.  
  360.  ( all  )  Restricted distribution.  These areas are privately distributed
  361.  (others)  and are *NOT* carried by the Filebone.  You must contact the FDN
  362.            head to obtain a feed.
  363.  
  364.  
  365.   Notification Messages:
  366.     If an error is encountered processing a user request, a message will be
  367.   sent  to  the sending site with an indication of the error.  The messages
  368.   will  be written as packets in the global OUT directory or the AREA's OUT
  369.   over-ride and will be packed/routed by the defined PACKER command.
  370.     For  certain  errors,  a  copy of the message will also be sent to YOU.
  371.   The packet will be placed in your currently defined inbound directory.
  372.  
  373.  
  374.   AreaMGR Commands:
  375.     XRAID supports a sub-set of the fsc-0057 Area Manager commands, as well
  376.   as the AllFix super-set.
  377.  
  378.     The AreaFix/Raid dash command syntax is NOT supported.  This means that
  379.   the  subject  field of the message must contain the site's XRAID password
  380.   ONLY.
  381.  
  382.     For security purposes certain commands defined in FSC-0057 or in use in
  383.   other  file  echo managers are NOT supported.  These are marked with a *.
  384.   See XRAID.hlp for a more complete description of the supported commands.
  385.  
  386.  
  387.   The confiduration entry ALLOWCMDS defines which of the more sensitive
  388. commands and functions XRaid will support.
  389.  
  390.  
  391.   Supported Commands:
  392.     +<areaname>     To connect to one or more FileEchos
  393.     -<areaname>     To disconnect from one or more FileEchos
  394.     %-ALL           To disconnect from ALL FileEchos. 
  395.     %+ALL           To connect to ALL FileEchos. FwdReq not permitted.    
  396.     %HELP           To request this help message
  397.     %STATUS         To request a status report
  398.                     Sends a report of site status and permissions
  399.     %QUERY          To request a list of FileEchos for which you are active
  400.                     Sends a full report of site status and permissions,
  401.                     linked areas, and permissions for each linked area.
  402.     %LIST           To request a list of fileechos available to you.
  403.     %LINKED         To request a list of fileechos to which you are
  404.                     connected.
  405.     %UNLINKED       To request a list of fileechos available to you,
  406.                     to which you are not already connected.
  407.     %PAUSE          To temporarily turn off all your FileEchos
  408.     %RESUME         To turn any inactive FileEchos back on
  409.     %NOTIFY=On/Off  To turn the notify function on/off for your system
  410.                     This disables the sending of the full REPORT.
  411.     %MESSAGE=On/Off To turn the message function on/off for your system
  412.                     This disables the sending of File ATTACH message.
  413.     %TICK=+/-FNC,+/-TIC,+/-TIC3D,+/-TO,+/-MD,+/-MA,+/-AD,+/-FN,+/-TI
  414.                     Toggle the TICK file option for your system
  415.                     '+' = On, '-' = Off
  416.                     FNC   - convert filenames to msdos 8.3 format
  417.                     TIC   - sending of TIC file
  418.                     TIC3D - 3D addressing
  419.                     TO    - TO line in TIC file
  420.                     MD    - multiple DESC lines in TIC file
  421.                     MA    - MAGIC line in TIC file
  422.                     AD    - AREADESC line in TIC file
  423.                     FN    - FULLNAME line in TIC file (in FNC enabled)
  424.                     TI    - AUTHOR, SOURCE etc.  lines in TIC file
  425.                     Please note that the %TICK command is VERY different
  426.                     from that of  AllFix.
  427.     %PASSWORD       To change your AreaMgr (RAID) password
  428.     %ECHOPASSWORD   To change your FileEcho (TIC) password
  429.  
  430.     %NOTE           Everything following a %NOTE, 
  431.     %COMMENT        %COMMENT or 
  432.     ---             or tear line is ignored
  433.  
  434.  
  435.  
  436.   Unsupported commands:
  437.     The  following  commands  as used in ALLFIX or defined in FSC-0057, are
  438.   presently  not  supported.  Support may be added in the future, however I
  439.   have  serious  reservations  about  some  of  these.   I  have added some
  440.   comments below.
  441.  
  442.  
  443.   * %-<GROUP>       To disconnect a group of file echos
  444.   * %+<GROUP>       To connect to a group of file echos
  445.     This is NOT such a simple change. One must keep in mind that this could
  446.     end  up  generating  HUNDREDS of requests to your uplink to add all the
  447.     echos to which you yourself are not connected.
  448.   
  449.   * %COMPRESSION=   Choose the compression type (ARC,ARJ,LZH,PAK,ZIP)
  450.   * %PACK=None/TIC/ALL
  451.                     Toggle the pack mode option for your system
  452.     These  commands  serve  no  purpose  in  Xraid.   IMHO,  re-archiving a
  453.     forwarded file invalidates security.  Archiving TIC files is just plain
  454.     dumb.
  455.  
  456.   * %RESEND <name>  To request that ALLFIX resend a certain file
  457.     This  function  is  handled by the %REQUEST and %UUREQUEST functions of
  458.     FQuery. Re-hatching to a single site is not supported.
  459.  
  460.  
  461.     Like  ALLFIX,  XRAID  does  NOT  support  ANY  of  the  FSC-0057 Remote
  462.   Maintainance  functions.   These  include  creation, deletion and tagname
  463.   change of FileEchos.
  464.  
  465.   The RaidList:
  466.     XScan  reads  packets  and scans them for netmail messages addressed to
  467.   XRAID  or  any of the defined aliases.  XScan scans each such message and
  468.   produces a line (max 64K each) per XRaid message.  XScan writes an output
  469.   file in APPEND mode, the filename as defined in XScan.cfg.
  470.  
  471.  
  472.   The format of a raidlist line is:
  473.  
  474.   dest_address|from_name|origin_address|password_from_subject|commands
  475.  
  476.   Note that '|' is used as a field separator.
  477.  
  478.   dest_address          - the address to which the message was sent
  479.   from_name             - the name of the sender (the user)
  480.   origin_address        - the address of the message originator
  481.   Password_from_subject - the password in the subject of the message
  482.   commands              - a ';' separated list of areamgr commands
  483.                           Each is separated with a ';' (semi-colon).  These
  484.                           commands  include  all lines that begin with '+',
  485.                           '-'  or  '%'.   If  no  commands were found, this
  486.                           field should be empty.
  487.  
  488.  
  489.